7.4.3 取得用戶鏈上位址

#簡單描述：取得使用者鏈上位址(如果不存在則建立)。

要求方式: POST
請求介面: https://网关域名/wallet-trade-merchant/merchant/user/get-address
請求媒體類型( JSON 資料格式 )Content-Type: application/json

查詢參數

參數名稱	類型	必填	參數意義	參數說明
`merchantId`	`int64`	是	商家 ID
`userId`	`string`	是	用戶 ID	商家本地用戶唯一 ID
`network`	`string`	是	主網	支援 TRON、BSC、POLYGON、ETHEREUM（可透過文件7.4.2取得）
`key`	`string`	是	商家 key	平台分配商家 key
`sign`	`string`	是	簽名參考（如何簽名）	詳見如何簽名規則

請求 json 範例

{
  "merchantId": "302992856974",
  "userId": "77",
  "network": "TRON",
  "key": "9yUreYgTRtit39Dy",
  "sign": "3876e3b40ce4938c3123f07cd5aecb8c"
}

回應 json 範例

{
  "code": 0,
  "data": {
    "address": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "merchantId": 308116064181,
    "network": {
      "avgBlockSecond": 3,
      "coinTotal": 2,
      "collectionNetworkConfirm": 3,
      "displayName": "Tron",
      "estimatedMinute": 1,
      "isDefault": null,
      "level": null,
      "logo": "https://dx-public-download.s3.ap-southeast-1.amazonaws.com/blockchain-logo/tron.png",
      "masterCoin": "TRX",
      "name": "TRON",
      "networkType": "TRON",
      "queryBaseUrl": "https://nile.tronscan.org/",
      "withdrawalNetworkConfirm": 3
    },
    "userId": "33"
  },
  "success": true,
  "message": null
}

回應data 參數說明

參數名稱	類型	參數意義	備註
`merchantId`	`int64`	商家 ID
`userId`	`string`	用戶 ID	商家本地用戶唯一 ID
`address`	`string`	鏈結位址	用戶的鏈結位址
`network`	`object`	鏈結主網資訊
└ name	`string`	主網名稱
└ queryBaseUrl	`string`	鏈上查詢網址
└ collectionNetworkConfirm	`int64`	儲值網確認次數
└withdrawalNetworkConfirm	`int64`	出款網路確認次數
└ coinTotal	`int64`	幣數量
└ masterCoin	`string`	主鏈幣種
└ networkType	`string`	主網類型(客戶端要保存位址類型時，請使用這個欄位)
└ masterCoin	`string`	主鏈幣種
└ avgBlockSecond	`num`	平均出塊時間(秒)
└ estimatedMinute	`num`	預計儲值到帳時間(分鐘)
└ displayName	`string`	主網顯示名稱
└ logo	`string`	logo 位址

回呼通知

當該用戶地址收到款項且訂單處理完成後，系統會向商家配置的預設回調位址發送通知訊息。

回呼位址配置

此介面不支援透過請求參數指定 notifyUrl，系統將回調商家後台配置的預設回呼位址。預設回呼位址由商家建立時提供，並可在營運管理後台進行維護。

回呼請求方式

HTTP Method

POST

Content-Type

application/json

回呼資料範例

依款項來源不同，回檔資料分為以下三種情況。

情況一：透過鏈上（其它錢包）轉帳至該位址

鏈上轉帳場景會傳回 blockchain 鏈上交易資訊。

{
  "amount": "6",
  "bizType": "PAYMENT_TRANSFER",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "senderAddress": "TPutFhYUQnrRxHSmKVwjp55vgk9QY6r5nS",
    "txId": "8265e6b65d8aad4727b55f79880941c1e22df54278a1f78b28d760eb7328a0d2",
    "txIndex": 0
  },
  "currency": "USDT",
  "merchantActualAmount": "38.86",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "38.86",
  "merchantUserId": "33",
  "notifyTime": 1783671086642,
  "orderCreateTime": 1783671075931,
  "orderId": "566708436246981",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "6",
  "userCurrency": "USDT",
  "userReceivableAmount": "6",
  "sign": "b0d2d52d8dc41af9373431fc8b2b2d6a"
}

情況二：透過內部錢包轉帳至該位址

內部錢包支付場景會傳回付款方的 walletUserId。

{
  "amount": "7",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "merchantActualAmount": "45.33",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "45.33",
  "merchantUserId": "33",
  "notifyTime": 1783671928955,
  "orderCreateTime": 1783671928956,
  "orderId": "566715422826565",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "7",
  "userCurrency": "USDT",
  "userReceivableAmount": "7",
  "walletUserId": 3,
  "sign": "08c9b45f19709f9d4e8ffbd5bc852eb9"
}

情況三：透過商家OpenAPI 提款至該位址

透過商家OpenAPI 建立提款訂單並提款至該地址時，會返回來源提款訂單資訊 fromWithdraw。

{
  "amount": "8",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "fromWithdraw": {
    "localOrderId": "17751376202610003",
    "merchantId": 308116064181,
    "orderId": 566716344475973
  },
  "merchantActualAmount": "51.81",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "51.81",
  "merchantUserId": "33",
  "notifyTime": 1783672041921,
  "orderCreateTime": 1783672041922,
  "orderId": "566716348211653",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "8",
  "userCurrency": "USDT",
  "userReceivableAmount": "8",
  "walletUserId": 2,
  "sign": "fc648e11787ccd94accd139453a3c69b"
}

**為滿足業務發展需要，回呼參數未來可能新增欄位。新增欄位預設參與簽章計算（除簽章規則中特別說明的欄位外），因此商家系統應具備向前相容能力，避免因欄位擴充導致驗簽失敗。 **

回呼參數說明

參數名稱	類型	參與簽名	參數意義	參數說明
`amount`	`decimal`	是	訂單金額
`bizType`	`enum`	是	業務類型	固定為 `PAYMENT_TRANSFER`
`blockchain`	`object`	是	鏈上交易資訊	僅鏈上轉帳儲值場景返回
└ network	`String`	是	主網
└ receiverAddress	`String`	是	接收位址
└ senderAddress	`String`	是	傳送位址
└ txId	`String`	是	交易 ID	區塊鏈交易哈希
└ txIndex	`int`	是	交易索引
`currency`	`String`	是	訂單幣種
`fromWithdraw`	`object`	是	來源提款訂單資訊	僅透過 OpenAPI 提款至該位址的場景返回
└ localOrderId	`String`	是	來源商家訂單號碼
└ merchantId	`int64`	是	來源提款訂單商家 ID
└ orderId	`int64`	是	來源平台訂單號碼
`merchantActualAmount`	`decimal`	是	商家實際收款金額
`merchantCurrency`	`String`	是	商家結算幣種
`merchantId`	`int64`	是	商家 ID
`merchantPaidAmount`	`decimal`	是	商家應收金額
`merchantUserId`	`String`	是	商家用戶 ID	對應獲取位址介面的 `userId`
`notifyTime`	`long`	是	回呼時間	回呼通知時間
`orderCreateTime`	`long`	是	訂單建立時間
`orderId`	`String`	是	訂單號碼	平台訂單號碼（唯一）
`status`	`String`	是	付款狀態	`SUCCESS`、`FAIL`
`type`	`String`	是	訂單類型	固定為 `PAYMENT`
`userAmount`	`decimal`	是	用戶實付金額
`userCurrency`	`String`	是	用戶幣種
`userReceivableAmount`	`decimal`	是	用戶應收金額
`walletUserId`	`int64`	是	錢包內部使用者 ID	內部錢包付款或透過 OpenAPI 提款至該位址時回傳
`sign`	`String`	否	簽章值	MD5 簽章（詳見簽章演算法）

status 狀態說明

狀態值	說明
`SUCCESS`	已完成
`FAIL`	已失敗

回呼回應要求

商家成功處理回呼後，必須回傳以下內容：

success

系統收到字串 success 後，視為回呼處理成功，不再重複發送。

回呼重試機制

若出現以下情況：

未收到回應
回傳內容不是 success
HTTP 請求異常
服務超時

系統將自動重試發送回呼通知。

最大重試次數

14次

重試間隔

建議商家系統依照 orderId 實現冪等處理，避免因重複回呼導致業務資料重複處理。

簽名校驗

收到回調通知後，商家必須先進行簽章驗證，驗證通過後再執行業務邏輯。簽章演算法與下單請求簽章規則完全一致，請參考《2. 如何簽章》。

驗簽流程

取得回呼參數中的 sign
從參數中移除 sign
將商家 key 放入參數
使用商家 secret 依簽章規則重新計算簽名
比較計算結果與回呼中的 sign 是否一致

只有驗簽成功後，才應處理訂單業務。

Java 驗簽範例

public void notify(JSONObject data) {

    log.info("收到回调通知：{}", data.toJSONString());

    String key = "your_key";
    String secret = "your_secret";

    String sign = data.getString("sign");

    data.put("key", key);
    data.remove("sign");

    String calculatedSign = SignUtils.getSign(data, secret);

    if (!calculatedSign.equals(sign)) {
        throw new DxBizException("签名验证失败");
    }
    // 业务处理逻辑
}

查詢參數​

請求 json 範例​

回應data 參數說明​

回呼通知

回呼位址配置​

回呼請求方式​

回呼資料範例​

情況一：透過鏈上（其它錢包）轉帳至該位址​

情況二：透過內部錢包轉帳至該位址​

情況三：透過 商家OpenAPI 提款至該位址​

回呼參數說明​

status 狀態說明​

回呼回應要求​

回呼重試機制​

最大重試次數​

重試間隔​